'\" p
.\" -*- nroff -*-
.TH "ovs-sim" 1 "ovs-sim" "Open vSwitch 2\[char46]5\[char46]3" "Open vSwitch Manual"
.fp 5 L CR              \\" Make fixed-width font available as \\fL.
.de TQ
.  br
.  ns
.  TP "\\$1"
..
.de ST
.  PP
.  RS -0.15in
.  I "\\$1"
.  RE
..
.SH "NAME"
.PP
ovs-sim \- Open vSwitch simulator environment
.SH "SYNOPSIS"
.PP
\fBovs\-sim\fR [\fIoption\fR]\[char46]\[char46]\[char46] [\fIscript\fR]\[char46]\[char46]\[char46]
.SH "DESCRIPTION"
.PP
\fBovs\-sim\fR provides a convenient environment for running one or
more Open vSwitch instances and related software in a sandboxed
simulation environment\[char46]
.PP
To use \fBovs\-sim\fR, first build Open vSwitch, then invoke it
directly from the build directory, e\[char46]g\[char46]:
.PP
.nf
\fB
.br
\fBgit clone https://github\[char46]com/openvswitch/ovs\[char46]git
.br
\fBcd ovs
.br
\fB\[char46]/configure
.br
\fBmake
.br
\fButilities/ovs\-sim
.br
\fB
.fi
.PP
When invoked in the most ordinary way as shown above,
\fBovs\-sim\fR does the following:
.RS
.IP 1. .25in
Creates a directory \fBsandbox\fR as a subdirectory of the
current directory (first destroying such a directory if it already
exists) and \fBcd\fRs into that directory\[char46]
.IP 2. .25in
Installs all of the Open vSwitch manpages into a \fBman\fR
subdirectory of \fBsandbox\fR and adjusts the \fBMANPATH\fR
environment variable so that \fBman\fR and other manpage viewers
can find them\[char46]
.IP 3. .25in
Creates a simulated Open vSwitch named \fBmain\fR and sets it
up as the default target for OVS commands, as if the following
\fBovs\-sim\fR commands had been run:
.IP
.nf
\fB
.br
\fB          sim_add main
.br
\fB          as main
.br
\fB
.fi
.IP
See \fBCommands\fR, below, for an explanation\[char46]
.IP 4. .25in
Runs any scripts specified on the command line (see
\fBOptions\fR below)\[char46]  The scripts can use arbitrary Bash
syntax, plus the additional commands described under
\fBCommands\fR, below\[char46]
.IP 5. .25in
If no scripts were specified, or if \fB\-i\fR or
\fB\-\-interactive\fR was specified, invokes an interactive
Bash subshell\[char46]  The user can use arbitrary Bash commands, plus the
additional commands described under \fBCommands\fR, below\[char46]
.RE
.PP
\fBovs\-sim\fR and the sandbox environment that it creates does not
require superuser or other special privileges\[char46]  Generally, it should not
be run with such privileges\[char46]
.SH "OPTIONS"
.PP
\fBovs\-sim\fR accepts the following options and arguments:
.RS
.TP
\fIscript\fR
Runs \fIscript\fR, which should be a Bash script, within a
subshell after initializing\[char46]  If multiple \fIscript\fR arguments
are given, then they are run in the order given\[char46]  If any
\fIscript\fR exits with a nonzero exit code, then
\fBovs\-sim\fR exits immediately with the same exit code\[char46]
.TP
\fB\-i\fR
.TQ .5in
\fB\-\-interactive\fR
By default, if any \fIscript\fR is specified, \fBovs\-sim\fR
exits as soon as the scripts finish executing\[char46]  With this option, or if
no scripts are specified, \fBovs\-sim\fR instead starts an
interactive Bash session\[char46]
.RE
.SH "COMMANDS"
.PP
Scripts and interactive usage may use the following commands implemented
by \fBovs\-sim\fR\[char46]  They are implemented as Bash shell functions
exported to subshells\[char46]
.SS "Basic Commands"
.PP
These are the basic commands for working with sandboxed Open vSwitch
instances\[char46]
.RS
.TP
\fBsim_add\fR \fIsandbox\fR
Starts a new simulated Open vSwitch instance named
\fIsandbox\fR\[char46]  Files related to the instance, such as logs,
databases, sockets, and pidfiles, are created in a subdirectory also
named \fIsandbox\fR\[char46]  Afterward, the \fBas\fR command
(see below) can be used to run Open vSwitch utilities in the context
of the new sandbox\[char46]
.IP
The new sandbox starts out without any bridges\[char46]  Use
\fBovs\-vsctl\fR in the context of the new sandbox to create a
bridge, e\[char46]g\[char46]:
.IP
.nf
\fB
.br
\fBsim_add hv0           # Create sandbox hv0\[char46]
.br
\fBas hv0                # Set hv0 as default sandbox\[char46]
.br
\fBovs\-vsctl add\-br br0  # Add bridge br0 inside hv0\[char46]
.br
\fB
.fi
.IP
The Open vSwitch instances that \fBsim_add\fR create enable
``dummy\(cq\(cq devices\[char46]  This means that bridges and interfaces can be
created with type \fBdummy\fR to indicate that they should be
totally simulated, without any reference to system entities\[char46]  In
fact, \fBovs\-sim\fR also configures Open vSwitch so that the
default \fBsystem\fR type of bridges and interfaces are
replaced by \fBdummy\fR devices\[char46]  Other types of devices,
however, retain their usual functions, which means that, e\[char46]g\[char46],
\fBvxlan\fR tunnels still act as tunnels (see
\fBREADME\-native\-tunneling\[char46]md\fR)\[char46]
.TP
\fBas\fR \fIsandbox\fR
Sets \fIsandbox\fR as the default simulation target for Open
vSwitch commands (e\[char46]g\[char46] \fBovs\-vsctl\fR,
\fBovs\-ofctl\fR, \fBovs\-appctl\fR)\[char46]
.IP
This command updates the beginning of the shell prompt to indicate
the new default target\[char46]
.TP
\fBas\fR \fIsandbox\fR \fIcommand\fR \fIarg\fR\[char46]\[char46]\[char46]
Runs the given \fIcommand\fR with \fIsandbox\fR as the
simulation target, e\[char46]g\[char46] \fBas hv0 ovs\-vsctl add\-br br0\fR runs
\fBovs\-vsctl add\-br br0\fR within sandbox \fBhv0\fR\[char46]
The default target is unchanged\[char46]
.RE
.SS "Interconnection Network Commands"
.PP
When multiple sandboxed Open vSwitch instances exist, one will inevitably
want to connect them together\[char46]  These commands allow for that\[char46]
Conceptually, an interconnection network is a switch that
\fBovs\-sim\fR makes it easy to plug into other switches in other
sandboxed Open vSwitch instances\[char46]  Interconnection networks are
implemented as bridges in the \fBmain\fR switch that
\fBovs\-sim\fR creates by default, so to use interconnection
networks please avoid working with \fBmain\fR directly\[char46]
.RS
.TP
\fBnet_add\fR \fInetwork\fR
Creates a new interconnection network named \fInetwork\fR\[char46]
.TP
\fBnet_attach\fR \fInetwork\fR \fIbridge\fR
Adds a new port to \fIbridge\fR in the default sandbox (as set
with \fBas\fR) and plugs it into the \fInetwork\fR
interconnection network\[char46]  \fInetwork\fR must already have been
created by a previous invocation of \fBnet_add\fR\[char46]  The default
sandbox must not be \fBmain\fR\[char46]
.RE
.SS "OVN Commands"
.PP
These commands interact with OVN, the Open Virtual Network\[char46]
.RS
.TP
\fBovn_start\fR
Creates and initializes the central OVN databases (both
\fBovn\-sb\fR(5) and \fBovn\-nb\fR) and starts an instance
of \fBovsdb\-server\fR for each one\[char46]  Also starts an instance of
\fBovn\-northd\fR\[char46]
.TP
\fBovn_attach\fR \fInetwork\fR \fIbridge\fR \fIip\fR [\fImasklen\fR]
First, this command attaches \fIbridge\fR to interconnection
network \fInetwork\fR, just like \fBnet_attach\fR
\fInetwork\fR \fIbridge\fR\[char46]  Second, it configures
(simulated) IP address \fIip\fR (with network mask length
\fBmasklen\fR, which defaults to 24) on \fIbridge\fR\[char46]
Finally, it configures the Open vSwitch database to work with OVN and
starts \fBovn\-controller\fR\[char46]
.RE
.SH "EXAMPLES"
.PP
The following creates a pair of Open vSwitch instances
\fBhv0\fR and \fBhv1\fR, adds a port named
\fBvif0\fR or \fBvif1\fR, respectively, to each
one, and then connects the two through an interconnection
network \fBn1\fR:
.PP
.nf
\fB
.br
\fBnet_add n1
.br
\fBfor i in 0 1; do
.br
\fB    sim_add hv$i
.br
\fB    as hv$i ovs\-vsctl add\-br br0 \-\- add\-port br0 vif$i
.br
\fB    as hv$i net_attach n1 br0
.br
\fBdone
.br
\fB
.fi
.PP
Here\(cqs an extended version that also starts OVN:
.PP
.nf
\fB
.br
\fBovn_start
.br
\fBovn\-nbctl lswitch\-add lsw0
.br
\fB
.br
\fBnet_add n1
.br
\fBfor i in 0 1; do
.br
\fB    sim_add hv$i
.br
\fB    as hv$i
.br
\fB    ovs\-vsctl add\-br br\-phys
.br
\fB    ovn_attach n1 br\-phys 192\[char46]168\[char46]0\[char46]`expr $i + 1`
.br
\fB    ovs\-vsctl add\-port br\-int vif$i \-\- set Interface vif$i external\-ids:iface\-id=lp$i
.br
\fB    ovn\-nbctl lport\-add lsw0 lp$i
.br
\fB    ovn\-nbctl lport\-set\-addresses lp$i f0:00:00:00:00:0$i
.br
\fBdone
.br
\fB
.fi
.PP
Here\(cqs a primitive OVN ``scale test\(cq\(cq (adjust the scale by
changing \fIn\fR in the first line :
.PP
.nf
\fB
.br
\fBn=200; export n
.br
\fBovn_start
.br
\fBnet_add n1
.br
\fBovn\-nbctl lswitch\-add br0
.br
\fBfor i in `seq $n`; do
.br
\fB    (sim_add hv$i
.br
\fB    as hv$i
.br
\fB    ovs\-vsctl add\-br br\-phys
.br
\fB    y=$(expr $i / 256)
.br
\fB    x=$(expr $i % 256)
.br
\fB    ovn_attach n1 br\-phys 192\[char46]168\[char46]$y\[char46]$x
.br
\fB    ovs\-vsctl add\-port br\-int vif$i \-\- set Interface vif$i external\-ids:iface\-id=lp$i) &
.br
\fB    case $i in
.br
\fB        *50|*00) echo $i; wait ;;
.br
\fB    esac
.br
\fBdone
.br
\fBwait
.br
\fBfor i in `seq $n`; do
.br
\fB    yy=$(printf %02x $(expr $i / 256))
.br
\fB    xx=$(printf $02x $(expr $i % 256))
.br
\fB    ovn\-nbctl lport\-add br0 lp$i
.br
\fB    ovn\-nbctl lport\-set\-addresses lp$i f0:00:00:00:$yy:$xx
.br
\fBdone
.br
\fB
.fi
.PP
When the scale test has finished initializing, you can watch the
logical ports come up with a command like this:
.PP
.nf
\fB
.br
\fBwatch \(cqfor i in `seq $n`; do if test `ovn\-nbctl lport\-get\-up lp$i` != up; then echo $i; fi; done\(cq
.br
\fB
.fi
